
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

    <title>Debugging with Leo &#8212; Leo 6.7.2 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
    <link rel="stylesheet" type="text/css" href="_static/custom.css" />
    
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    
    <script src="_static/sidebar.js"></script>
    
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Leo’s Console Gui" href="console-gui.html" />
    <link rel="prev" title="Writing Plugins" href="writingPlugins.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="console-gui.html" title="Leo’s Console Gui"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="writingPlugins.html" title="Writing Plugins"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="leo_toc.html">Leo 6.7.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="intermediatetopics.html" accesskey="U">Advanced Topics</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Debugging with Leo</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="debugging-with-leo">
<h1>Debugging with Leo<a class="headerlink" href="#debugging-with-leo" title="Permalink to this heading">¶</a></h1>
<p>This chapter discusses debugging Python scripts with Leo.
Be aware of the distinction between <strong>Leo-specific</strong> scripts and <strong>general</strong> scripts.
Leo-specific scripts access data in the Leo outline in which they are contained;
general scripts do not.</p>
<div class="contents local topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#using-g-trace-and-g-pdb" id="id1">Using g.trace and g.pdb</a></p></li>
<li><p><a class="reference internal" href="#settings-for-winpdb" id="id2">Settings for winpdb</a></p></li>
<li><p><a class="reference internal" href="#debugging-scripts-with-winpdb" id="id3">Debugging scripts with winpdb</a></p>
<ul>
<li><p><a class="reference internal" href="#the-debug-command" id="id4">The debug command</a></p></li>
<li><p><a class="reference internal" href="#the-execute-script-command-with-explicit-debugger-breaks" id="id5">The execute-script command with explicit debugger breaks</a></p></li>
</ul>
</li>
</ul>
</div>
<section id="using-g-trace-and-g-pdb">
<h2><a class="toc-backref" href="#id1">Using g.trace and g.pdb</a><a class="headerlink" href="#using-g-trace-and-g-pdb" title="Permalink to this heading">¶</a></h2>
<p>Inserting g.trace statements in my Python code is usually my first debugging choice. The g.trace statement prints the name of the function in which the call to g.trace occurs, followed by the value of its arguments. The output of the g.trace goes to the console, so you must <a class="reference external" href="installing.html#running-leo-from-a-console-window">run Leo in a console</a> to use g.trace.</p>
<p>Inserting and deleting g.trace statements is fast, provided that your <a class="reference external" href="FAQ.html#how-can-i-use-leo-to-develop-leo-itself">work flow</a> makes it easy to restart the program under test. As a result, using g.trace statements is similar to setting tracepoints in a debugger, with the advantage that (disabled) tracepoints remain in the source code for future use. You will find many examples of using g.trace throughout Leo’s source code.</p>
<p>My second choice is using g.pdb to set breakpoints for the <a class="reference external" href="https://docs.python.org/3/library/pdb.html">pdb</a> debugger. Pdb uses the console for all interaction, so you must <a class="reference external" href="installing.html#running-leo-from-a-console-window">run Leo in a console</a>. See the <a class="reference external" href="FAQ.html#how-can-i-use-python-s-pdb-debugger-with-leo">FAQ</a> for a discussion of both g.trace and g.pdb.</p>
</section>
<section id="settings-for-winpdb">
<h2><a class="toc-backref" href="#id2">Settings for winpdb</a><a class="headerlink" href="#settings-for-winpdb" title="Permalink to this heading">¶</a></h2>
<p>The following settings in leoSettings.leo control debugger operation. The settings shown here will be assumed to be in effect throughout this chapter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@string</span> <span class="n">debugger_kind</span> <span class="o">=</span> <span class="n">winpdb</span>
</pre></div>
</div>
<p>This setting controls what debugger the ‘Debug Script’ script button uses. Eventually this setting will control what debugger the debug command uses:: At present the only valid value is ‘winpdb’</p>
<blockquote>
<div><p>&#64;bool write_script_file = True</p>
</div></blockquote>
<p>True: The execute script command writes the script to be executed to a file, then executes the script using Python’s execFile function. The script_file_path setting specifies the path to this file. False (legacy): The execute script command uses Python’s exec command to execute the script.</p>
<p>&#64;string script_file_path = ../test/scriptFile.py</p>
<p>The path to the file to be written by the execute-script command. Notes:</p>
<ul class="simple">
<li><p>This setting has effect only if the write_script_file setting is True.</p></li>
<li><p>Use / as the path delimiter, regardless of platform.</p></li>
<li><p>The default path is ../test/scriptFile.py if no path is given.</p></li>
<li><p>The path starts at g.app.loadDir, so for example ../test/scriptFile.py is equivalent to leo/test/scriptFile.py.</p></li>
<li><p>The filename should end in .py.</p></li>
</ul>
<p>&#64;string debugger_path = None</p>
</section>
<section id="debugging-scripts-with-winpdb">
<h2><a class="toc-backref" href="#id3">Debugging scripts with winpdb</a><a class="headerlink" href="#debugging-scripts-with-winpdb" title="Permalink to this heading">¶</a></h2>
<p>The following three section discuss three ways of debugging scripts with <a class="reference external" href="http://www.digitalpeers.com/pythondebugger/">winpdb</a>. The first two sections tell how to debug general scripts; the last section tells how to debug Leo-specific scripts.</p>
<p><a class="reference external" href="http://www.digitalpeers.com/pythondebugger/">winpdb</a> and its documentation have been improved recently. For more details, see the <a class="reference external" href="http://www.digitalpeers.com/pythondebugger/embedded.htm">embedded winpdb</a> docs. The discussion of embedded debugging may have been written specifically with Leo in mind.</p>
<section id="the-debug-command">
<h3><a class="toc-backref" href="#id4">The debug command</a><a class="headerlink" href="#the-debug-command" title="Permalink to this heading">¶</a></h3>
<p>This way of debugging can only be used for general scripts, not leo-specific scripts. The debug command writes the script to scriptFile.py and invokes winpdb. winpdb opens and is already ‘attached’ to the script to be debugged. You can single-step as you like. Leo continues to run, but killing the debugger will also kill Leo.</p>
</section>
<section id="the-execute-script-command-with-explicit-debugger-breaks">
<h3><a class="toc-backref" href="#id5">The execute-script command with explicit debugger breaks</a><a class="headerlink" href="#the-execute-script-command-with-explicit-debugger-breaks" title="Permalink to this heading">¶</a></h3>
<p>This way of debugging scripts allows winpdb to debug scripts that use c, g and p. A bit more work is needed because winpdb does not start automatically. Here are step-by step instructions:</p>
<ol class="arabic">
<li><p>Insert the following two lines of code at the start of the script to be debugged:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">rpdb2</span>
<span class="n">rpdb2</span><span class="o">.</span><span class="n">start_embedded_debugger</span><span class="p">(</span><span class="s1">&#39;go&#39;</span><span class="p">,</span><span class="n">fAllowUnencrypted</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p>Execute Leo’s execute-script command (<em>not</em> the debug command). Leo will appear to hang: start_embedded_debugger is waiting for <em>another</em> copy of winpdb to ‘attach’ to the script’s process. The default timeout is 5 minutes, after which an exception gets thrown.</p></li>
<li><p>Start winpdb explicitly by executing something like the following in a console:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">/</span><span class="n">Python26</span><span class="o">/</span><span class="n">Scripts</span><span class="o">/</span><span class="n">_winpdb</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">t</span>
</pre></div>
</div>
<p>The -t option tells winpdb that no encoding of password is necessary.
The password is specified in the call to rpdb2.start_embedded_debugger in your script.
In our example, the password is ‘go’.</p>
</li>
<li><p>Use winpdb’s <a class="reference external" href="File:Attach">File:Attach</a> command to attach winpdb to Leo. Specify the password as ‘go’ and you will see the scriptFile.py containing your entire script. You can now execute or single-step through the script. To repeat, c, g and p are defined, so you can debug any script this way.</p></li>
</ol>
</section>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="leo_toc.html">
              <img class="logo" src="_static/LeoLogo.svg" alt="Logo"/>
            </a></p>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="writingPlugins.html"
                          title="previous chapter">Writing Plugins</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="console-gui.html"
                          title="next chapter">Leo’s Console Gui</a></p>
  </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>

      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="console-gui.html" title="Leo’s Console Gui"
             >next</a> |</li>
        <li class="right" >
          <a href="writingPlugins.html" title="Writing Plugins"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="leo_toc.html">Leo 6.7.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="intermediatetopics.html" >Advanced Topics</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Debugging with Leo</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 1997-2023, Edward K. Ream.
      Last updated on February 28, 2023.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
    </div>
  </body>
</html>